home *** CD-ROM | disk | FTP | other *** search
/ PC Graphics Unleashed / PC Graphics Unleashed.iso / xa / vsa256.txt < prev    next >
Text File  |  1994-07-30  |  69KB  |  1,705 lines
  1.                                      
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.                                   VSA256
  10.                              Graphics Library
  11.                                      
  12.                              For C Programmers
  13.                                      
  14.                                 Version 3.0
  15.                                July 30, 1994
  16.                                      
  17.                                      
  18.                     Copyright Spyro Gumas, 1992 - 1994.
  19.                             All Rights Reserved
  20.                                      
  21.                                      
  22.                                      
  23.                                      
  24.                                      
  25.                                      
  26.                      Look what You get for Registering!!
  27.  
  28.           -    Royalty Free Use of VSA256 in Your Programs!
  29.           -    3D Graphics Library!
  30.           -    Graphics Mouse Library!
  31.           -    Joystick Library & Source Code!
  32.           -    Image Processing Library & Source Code!
  33.           -    32 Bit WATCOM C Compiler compatible library!
  34.           -    On line support through CompuServe!
  35.           -    Printed Users Manual and Software Disk!
  36.           -    Half Price upgrade to next version!
  37.  
  38.  
  39.  
  40.  
  41.                          (See Page 6 for Details)
  42.  
  43.                                 
  44.                                 
  45.                                 
  46.                                 
  47.                                 
  48.                                 
  49.                                 
  50.  
  51.  
  52.  
  53.  
  54.                                 Page: 1
  55.                                    
  56. 1.0 Introduction                                       4
  57.   1.1 Revision History                                 4
  58.   1.2 Benefits of Registering                          6
  59.   1.3 Distribution Files                               7
  60. 2.0 The Programming Environment                        8
  61.   2.1 Setting Up The VESA Environment                  8
  62.   2.2 Global Graphics Parameters                       8
  63.   2.3 Compiler Compatibility                           9
  64. 3.0 Function Descriptions                              10
  65.   3.1 VESA Configuration Functions                     10
  66.      3.1.1 vsa_set_svga_mode                           10
  67.      3.1.2 vsa_get_svga_mode                           11
  68.      3.1.3 vsa_init                                    11
  69.   3.2 Miscellaneous Functions                          12
  70.      3.2.1 vsa_set_display_start                       12
  71.      3.2.2 vsa_get_display_start                       13
  72.      3.2.3 vsa_wait_vsync                              13
  73.   3.3 Attribute Functions                              13
  74.      3.3.1 vsa_set_color                               13
  75.      3.3.2 vsa_set_text_color                          14
  76.      3.3.3 vsa_set_clip_mode                           14
  77.      3.3.4 vsa_set_viewport                            14
  78.   3.4 Color Look Up Table Functions                    15
  79.      3.4.1 vsa_read_color_register                     15
  80.      3.4.2 vsa_write_color_register                    15
  81.      3.4.3 vsa_read_color_block                        15
  82.      3.4.4 vsa_write_color_block                       16
  83.   3.5 Text Functions (New-Vector Stroked!)             16
  84.      3.5.1 vsa_set_text_cursor                         17
  85.      3.5.2 vsa_get_text_cursor                         17
  86.      3.5.3 vsa_set_text_scale                          17
  87.      3.5.4 vsa_set_text_cursor_mode                    18
  88.      3.5.5 vsa_write_string                            18
  89.      3.5.6 vsa_write_string_alt                        19
  90.   3.6 Basic Drawing Functions                          19
  91.      3.6.1 vsa_move_to                                 19
  92.      3.6.2 vsa_set_pixel                               19
  93.      3.6.3 vsa_get_pixel                               20
  94.      3.6.4 vsa_line_to                                 20
  95.      3.6.5 vsa_gouraud_line                            20
  96.      3.6.6 vsa_rect_fill                               21
  97.      3.6.7 vsa_rect                                    21
  98.      3.6.8 vsa_triangle_fill                           21
  99.      3.6.9 vsa_shaded_triangle                         21
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.                                 Page: 2
  110.                                    
  111.      3.6.10 vsa_h_line                                 22
  112.      3.6.11 vsa_v_line                                 22
  113.   3.7 Specialized Drawing Functions                    22
  114.      3.7.1 vsa_raster_line                             22
  115.      3.7.2 vsa_get_raster_line                         23
  116.      3.7.3 vsa_image_size                              23
  117.      3.7.4 vsa_get_image                               24
  118.      3.7.5 vsa_put_image                               24
  119. 4.0 Nitty Gritties                                     25
  120.   4.1 Registration Information                         25
  121.   4.2 Software License                                 26
  122.   4.3 Disclaimer                                       27
  123.   4.4 Technical Support                                27
  124. 5.0 Graphics Library Extensions                        28
  125. 6.0 Appendix                                           29
  126.   6.1 VSA.H Include File                               29
  127.   6.2 VSA_FONT.H Include File                          31
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.                                 Page: 3
  165.                                    
  166. ----- 1.0 Introduction
  167.  
  168.      The VSA256 Graphics Library provides a C programmer with the tools
  169. necessary to generate graphics output on a video adapter running with the
  170. Video Electronics Standards Association (VESA) version 1.2 BIOS extensions.
  171. The VESA BIOS extensions standardize the Super VGA (SVGA) graphics
  172. environment.  The name "VSA256" reflects the fact that this library is
  173. aimed at supporting the 256 color video modes 100h, 101h, 103h, 105h, and
  174. 107h defined within the VESA standard (See table in section 3.1.1).
  175.  
  176.  
  177. ----- 1.1 Revision History
  178.  
  179. Version 1.0 is the original SHAREWARE version of the VSA256 Graphics
  180. Library.
  181.  
  182. Version 1.1 is the SHAREWARE version of the VSA256 Graphics Library which
  183. corrected some compiler compatibility problems and added the
  184. vsa_get_raster_line function which was necessary for the TIFF256 Graphics
  185. Library Extensions.  Some drawing errors were also corrected.
  186.  
  187. Version 2.0b is the REGISTERED version of the VSA256 Graphics Library.
  188. Whereas the VSA256 Graphics Library Version 1.x is shareware, Version 2.0b
  189. IS NOT shareware and may only be used in accordance with the terms of the
  190. purchase agreement.  The major changes between version 1.1 and 2.0b are
  191. listed below:
  192.  
  193.      -    3 to 1 speed up of vsa_line_to
  194.      -    2 to 1 speed up of vsa_raster_line
  195.      -    3 to 1 speed up of vsa_h_line
  196.      -    New routine, vsa_get_raster_line
  197.      -    New routine, vsa_gouraud_line
  198.      -    New routine, vsa_triangle_fill
  199.      -    New routine, vsa_shaded_triangle (Gouraud)
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.                                 Page: 4
  220.                                    
  221. Version 3.0 is presented to the general public in the true spirit of
  222. shareware.  This revision is the full-up version of the  VSA256 Graphics
  223. Library.  I  no longer maintain a separate registered version of this
  224. library.  Version 3.0 of the VSA256 Graphics Library is presented as
  225. Shareware with high hopes that the programmers who use this library will
  226. feel good about sending in the registration fee of $29.  The major changes
  227. between version 2.0b and 3.0 are listed below:
  228.  
  229. - Added Viewport Clipping to all drawing functions.
  230. - Added BitBLT drawing functions.
  231. - Added Vector Text: Infinitely scaleable and set to
  232.   nearest pixel, fonts are fully user definable!
  233. - Now text routines work with ALL video adapters.
  234. - Now works with Small, Medium, Compact Large memory
  235.   models with Borland (Already did so with Microsoft).
  236. - Fixed "unresolved external _fstrlen" linker error
  237.   with Turbo C.
  238. - Made all functions in VSA.H external, no more
  239.   "Multiple Declaration" warnings.
  240. - New routine, vsa_set_clip_mode.
  241. - New routine, vsa_set_viewport.
  242. - New routine, vsa_set_text_scale.
  243. - New routine, vsa_image_size.
  244. - New routine, vsa_get_image.
  245. - New routine, vsa_put_image.
  246. - New routine, vsa_get_pixel.
  247. - New routine, vsa_get_text_cursor.
  248. - New routine, vsa_wait_vsync.
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.                                 Page: 5
  275.                                    
  276. ----- 1.2 Benefits of Registering
  277.  
  278.      If you use this program beyond an initial evaluation period, you must
  279. register your use with a $29 remittance to the author .. me.  In addition
  280. to the good feeling that you get for sustaining a late night hacking
  281. obsession, you get the following benefits for registering:
  282.  
  283. 1)        Royalty Free Use of VSA256 in Your Programs! Feel free to
  284.           distribute your programs for profit with no royalty fees.  See
  285.           section 4.2.
  286.  
  287. 2)        3D Graphics Library!   Don't live in a flat world.  Add the
  288.           missing 3rd dimension to your creations.  This library lets you
  289.           create 3d objects, set your view point, and perform 3d
  290.           transformations including scale, offset, and rotation.  Supports
  291.           wireframe, solid, and Gouraud shaded objects.
  292.  
  293. 3)        Graphics Mouse Library!   Use this library to integrate Mouse
  294.           input with your graphics applications.  Get precise updates of
  295.           mouse position, update screen cursor, read mouse buttons, and
  296.           more.  Invent your own graphical user interface, give your apps
  297.           that professional feel, have tons of fun!
  298.  
  299. 4)        Joystick Library with Source Code!   Integrate Joystick input
  300.           with your graphics applications.  Write a flight simulator, boat
  301.           driver, or your own unique use of this agile input device.
  302.  
  303. 5)        IMP256 Image Processing Library and Source Code!  With this
  304.           library you can learn all about image sharpening, embossing,
  305.           blurring, color balancing, and enhancement.
  306.  
  307. 6)        32 Bit WATCOM C Compiler compatible VSA256 and TIFF256 libraries!
  308.           Get the edge on performance.
  309.  
  310. 7)        On line support through CompuServe.
  311.  
  312. 8)        Printed Users Manual and Current Version Software on Disk.
  313.  
  314. 9)        One Half Price Upgrade to the next version, as it becomes
  315.           available.
  316.  
  317.  
  318.  
  319.  
  320.                                 
  321.                                 
  322.                                 
  323.                                 
  324.                                 
  325.                                 
  326.                                 
  327.                                 
  328.                                 
  329.                                 Page: 6
  330.                                    
  331.                                     AND
  332. As if that's not enough, for a measly $15 more,  you will get:
  333.  
  334. 10)       TIFF256 Graphics Library Extensions.  This extension to the
  335.           VSA256 library lets you read TIFF formatted graphic image files,
  336.           display them, modify them, and write them back to disk.
  337.           Furthermore, anything that you create and display on the screen
  338.           can be saved as a TIFF image file.
  339.  
  340.                                     AND
  341.  
  342. 11)       The following public domain full color TIFF image files to get
  343.           you started:
  344.  
  345.                          VENUS.TIF
  346.                          EARTH.TIF
  347.                          MOON.TIF
  348.                          MARS.TIF
  349.                          SATURN.TIF
  350.                          NEPTUNE.TIF
  351.                          SHUTTLE.TIF
  352.                          ASTRONTS.TIF
  353.                          WEATHER.TIF
  354.                          MANDRILL.TIF
  355.  
  356.                (What, no Ginsu Knife Set?)
  357.  
  358. ----- 1.3 Distribution Files
  359.  
  360.      The distribution of the VSA256 Graphics Library Version 3.0 consists
  361. of the 9 files listed below plus the drivers listed in Section 2.1.  These
  362. files are archived in the file VSA256.ZIP.  To extract, just type 'PKUNZIP
  363. VSA256' in the directory that you want the files extracted to.
  364.  
  365. VSA_DEMO.C     VSA256 Demonstration program (Source Code).
  366. VSA_DEMO.EXE   VSA256 Demonstration program (Executable).
  367. VSA256MS.LIB   VSA256 Graphics Library (Microsoft C compatible).
  368. VSA256BC.LIB   VSA256 Graphics Library (Borland C Compatible).
  369. VSA.H          VSA256 Include file required in your program.
  370. VSA_FONT.H     VSA256 Include file required in your program.
  371. VSA256.TXT     This text document.
  372. ORDER.TXT      A text file order form, registration and upgrades.
  373. README.TXT     A text file with important info.
  374.  
  375.  
  376.  
  377.                                 
  378.                                 
  379.                                 
  380.                                 
  381.                                 
  382.                                 
  383.                                 
  384.                                 Page: 7
  385.                                    
  386. ----- 2.0 The Programming Environment
  387.  
  388. ----- 2.1 Setting Up The VESA Environment
  389.  
  390.      The VSA256 Graphics Library works with any (any?) IBM PC, XT, AT or
  391. compatible computer equipped with a VESA compatible SVGA video adapter card
  392. capable of 256 colors.  Most  of the video cards sold today are VESA
  393. compatible with the VESA BIOS built in to the card.  A math coprocessor
  394. chip is not required.
  395.      For older SVGA video cards which are not VESA compatible, the VESA
  396. BIOS Extensions must be loaded as a Terminate and Stay Resident (TSR)
  397. program before using the VSA256 Graphics Library.  This is accomplished by
  398. executing the appropriate driver or adding it to your AUTOEXEC.BAT file.
  399. If your video adapter card came with a VESA driver, use it.  Otherwise use
  400. one of the drivers provided depending on the video adapter card installed
  401. in the PC as follows:
  402.  
  403. APPIAN         \APPIAN\APVESA.EXE
  404. ATI            \ATI\VESA.COM
  405. C&T            \C&T\VESA451.COM (or VESA452.COM)
  406. CIRRUS         \CIRRUS\CRUSVESA.COM
  407. EVEREX         \EVEREX\EVRXVESA.COM
  408. GENOA          \GENOA\VESA.COM
  409. OAK            \OAK\37VESA.COM (or67VESA.COM)
  410. ORCHID         \ORCHID\ORCHDVSA.COM
  411. PARADISE       \PARADISE\VESA.EXE
  412. SIGMA          \SIGMA\SIGVESA.COM
  413. STB            \STB\STB-VESA.COM
  414. TECMAR         \TECMAR\VGAVESA.COM
  415. TRIDENT        \TRIDENT\VESA.EXE
  416. VIDEO7         \VIDEO7\V7VESA.COM
  417.  
  418. ----- 2.2 Global Graphics Parameters
  419.  
  420.      The VSA.H and VSA_FONT.H  files are used as include files during 
  421. program development.  These files includes all of the function prototypes 
  422. and define the global graphics parameters that describe the specific video 
  423. adapter installed in the PC (See Section 6).  The global graphics parameters 
  424. are initialized by the vsa_init function and are described below:
  425.  
  426. XResolution:        Unsigned, the number of screen pixels across (x
  427.                     dimension).
  428. YResolution:        Unsigned, the number of screen pixels high (y
  429.                     dimension).
  430. XCharResolution:    Unsigned, the number of screen characters cross (x
  431.                     dimension).
  432. YCharResolution:    Unsigned, the number of screen characters high (y
  433.                     dimension).
  434.  
  435.  
  436.                                 
  437.                                 
  438.                                 
  439.                                 Page: 8
  440.                                    
  441. XCharSize:          Unsigned char, the character drawn cell width.
  442. YCharSize:          Unsigned char, the character drawn cell  height.
  443. BitsPerPixel:       Unsigned char, the number of bits per pixel.
  444. XLeft:              Int, the left edge of the screen clipping Viewport.
  445. YTop:               Int, the top edge of the screen clipping Viewport.
  446. XRight:             Int, the right edge of the screen clipping viewport.
  447. YBottom:            Int, the bottom edge of the screen clipping Viewport.
  448. Text_X_Scale:       Float, multiplies XCharBase to get text width in pixels.
  449. Text_Y_Scale:       Float, multiplies YCharBase to get text height in pixels.
  450. XCharBase:          Unsigned, the fundamental text character width.
  451. YCharBase:          Unsigned, the fundamental text character height.
  452. ASC[96][72]:        Unsigned Char, the 2D array of character vertices.
  453.  
  454.      Note that there is a fundamental difference between how you use VSA.H 
  455. and how you use VSA_FONT.H.  The function prototypes and the global 
  456. parameter declarations are all "extern" in VSA.H.  This means that you can 
  457. plop VSA.H into the top of each and every code module (file) which is part
  458. of your project.  VSA_FONT.H, on the other hand, declares and initializes 
  459. the 'ASC[][]' array.  Since I want you, the programmer, to have access to 
  460. the font definitions, I couldn't make these parameter declarations "extern".  
  461. What this means for you is that if you have multiple code modules (files), 
  462. only include VSA_FONT.H in one of the files.  Then put the following two 
  463. lines of code at the top of each and every other code module (file) in your 
  464. project:
  465.  
  466.              extern unsigned XCharBase,YCharBase;
  467.              extern unsigned char ASC[][];
  468.  
  469. ----- 2.3 Compiler Compatibility
  470.  
  471.      The VSA256MS.LIB was compiled using Microsoft's Quick C 2.5 and it
  472. seems to also work well with Microsoft C 6.0 and 7.0.  I have received
  473. reports of compatibility problems with Microsoft C 5.0.
  474.      The VSA256BC.LIB was compiled using Borland's C/C++ 3.1 and it seems
  475. to also work well with Borland C/C++ 3.0 and 4.0.  I have received
  476. conflicting reports of compatibility problems with Borland's Turbo C 2.0
  477. and 3.0.
  478.      I appreciate any feedback that programmers send me along these lines
  479. so that I can continue to improve this product.
  480.  
  481.                      Important Note for Borland Users:
  482.  
  483.      You MUST set the -Fs compiler option.  This tells the compiler to
  484. assume that the Stack Segment equals the Data Segment.  In the Programmers
  485. IDE, you go to Options / Compiler / Code Generation and select "Always"
  486. under the option "Assume SS Equals DS".
  487.      Why?  The VSA256 library can be used in Tiny, Small, Medium, Compact,
  488. and Large memory models in both the Microsoft and Borland environments.
  489. Microsoft always puts the Stack Segment in the first Data Segment, but
  490. Borland sets up a separate Stack Segment (for Compact and Large memory
  491. models) unless you specify the -Fs option.  Failing to set -Fs will result
  492. in a "Stack Overflow!" error when running code compiled in Compact or Large
  493. memory models.
  494.                                 Page: 9
  495.                                    
  496. ----- 3.0 Function Descriptions
  497.  
  498.      This section describes the functions supported in the VSA256 Graphics
  499. Library.  To use these functions, link your program with the appropriate
  500. library listed below depending on the compiler being used.
  501.  
  502.           Borland C, C++ or Turbo C     -    VSA256BC.LIB
  503.           Microsoft C or Quick C        -    VSA256MS.LIB
  504.  
  505.      In the following sections each function is listed along with a
  506. definition of its inputs and return values.  A description is provided
  507. followed by the version in which the function became available.  Finally,
  508. if applicable, comments are provided.
  509.  
  510. ----- 3.1 VESA Configuration Functions
  511.  
  512. ----- 3.1.1 vsa_set_svga_mode(video_mode)
  513.  
  514. Inputs:   unsigned video_mode;
  515.  
  516. Returns:  unsigned fail_flag;
  517.  
  518. Description:   This routine sets the video mode.  The mode number may be
  519.           any of the standard VESA SVGA mode numbers as defined in the
  520.           tables below.  The mode is passed to this routine through the
  521.           'video_mode' parameter.  This routine returns a 'fail_flag' = 0
  522.           if the call was a success (a 1 for failure).  It should be noted
  523.           that this routine will also work with standard MDA, CGA, EGA, and
  524.           VGA mode numbers, however the rest of the VSA256 functions will
  525.           not necessarily work.
  526.  
  527. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  528.  
  529. WARNING: Use vsa_init Instead (Section 3.1.3)!  If you don't use vsa_init,
  530. then the rest of the routines won't work because they depend on the global
  531. parameters initialized by vsa_init;
  532.  
  533.                            VESA SVGA VIDEO MODES
  534.  
  535. GRAPHICS       Mode      Resolution          Colors
  536.                100h      640x400             256
  537.                101h      640x480             256
  538.                102h      800x600             16
  539.                103h      800x600             256
  540.                104h      1024x768            16
  541.  
  542.  
  543.                                 
  544.                                 
  545.                                 
  546.                                 
  547.                                 
  548.                                 
  549.                                 Page: 10
  550.                                    
  551.                105h      1024x768            256
  552.                106h      1280x1024           16
  553.                107h      1280x1024           256
  554.  
  555. TEXT           Mode      Columns             Rows
  556.                108h      80                  60
  557.                109h      132                 25
  558.                10Ah      132                 43
  559.                10Bh      132                 50
  560.                10Ch      132                 60
  561.  
  562. ----- 3.1.2 vsa_get_svga_mode(video_mode)
  563.  
  564. Inputs:   unsigned far *video_mode;
  565.  
  566. Returns:  unsigned fail_flag;
  567.  
  568. Description:   This routine gets the current video mode.  The mode is
  569.           returned to the calling routine via the 'video_mode' pointer.
  570.           The mode number may be any of the standard VESA SVGA mode numbers
  571.           as defined in Section 3.1.1.  This routine returns a 'fail_flag'
  572.           = 0 if the call was a success (a 1 for failure).
  573.  
  574. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  575.  
  576. Comments: Works in all VESA video modes.
  577.           Also works in MDA, CGA, EGA and VGA Modes.
  578.  
  579. ----- 3.1.3 vsa_init(video_mode)
  580.  
  581. Inputs:   unsigned video_mode;
  582.  
  583. Returns:  unsigned fail_flag;
  584.  
  585. Description:   This routine sets the video mode and initializes the VESA
  586.           graphics environment.  This routine must be called prior to the
  587.           use of any of the routines in Sections 3.4 through 3.7.  The mode
  588.           number may be any of the standard VESA SVGA mode numbers as
  589.           defined in Section 3.1.1.  If the mode number is not a VESA SVGA
  590.           mode number, this routine will still set the desired video mode,
  591.           however, the VESA graphics environment will not be initialized
  592.  
  593.  
  594.                                 
  595.                                 
  596.                                 
  597.                                 
  598.                                 
  599.                                 
  600.                                 
  601.                                 
  602.                                 
  603.                                 
  604.                                 Page: 11
  605.                                    
  606.           and subsequent calls to drawing routines will produce
  607.           unpredictable results.  The mode is passed to this routine
  608.           through the 'video_mode' parameter.  This routine returns a
  609.           'fail_flag' = 0 if the call was a success.  For failures, the
  610.           'fail_flag' has the following meaning:
  611.  
  612.           1  - Can not get Super VGA Environment information.
  613.                Make sure VESA BIOS TSR is loaded.
  614.           2  - VESA BIOS TSR not loaded.  Need to load one.
  615.           3  - Specified Video Mode not supported by this video
  616.                card.  Try another mode.
  617.           4  - Specified Video Mode was set but it is not one
  618.                of the VESA standard modes.  VSA256 may not  function
  619.                properly.
  620.           5  - Can not get Super VGA Video Mode Data.  Make
  621.                sure correct VESA BIOS TSR is loaded.
  622.  
  623. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  624.  
  625. Comments:     Starting with Version 3.0, VSA256 no longer prints out error
  626.           messages automatically to the screen.  The programmer gets full
  627.           status feed back via the 'fail_flag' and can do as he/she sees
  628.           fit.
  629.               Also note that VSA256 no longer cares if the specific VESA
  630.           BIOS Extensions TSR being used supports text functions.  This is
  631.           due to the new implementation of text using vector strokes (see
  632.           vsa_write_string).
  633.  
  634. ----- 3.2 Miscellaneous Functions
  635.  
  636. ----- 3.2.1 vsa_set_display_start(x_strt,y_strt)
  637.  
  638. Inputs:   unsigned x_strt,y_strt;
  639.  
  640. Returns:  unsigned fail_flag;
  641.  
  642. Description:   This routine sets the current start pixel address which is
  643.           mapped to the upper left corner of the display.  This routine
  644.           returns a 'fail_flag' = 0 if the call was a success (a 1 for
  645.           failure).
  646.  
  647. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  648.  
  649.  
  650.  
  651.                                 
  652.                                 
  653.                                 
  654.                                 
  655.                                 
  656.                                 
  657.                                 
  658.                                 
  659.                                 Page: 12
  660.                                    
  661. ---- 3.2.2 vsa_get_display_start(x_strt,y_strt)
  662.  
  663. Inputs:   unsigned far *x_strt, far *y_strt;
  664.  
  665. Returns:  unsigned fail_flag;
  666.  
  667. Description:   This routine gets the current start pixel address which is
  668.           mapped to the upper left corner of the display.  This routine
  669.           returns a 'fail_flag' = 0 if the call was a success (a 1 for
  670.           failure).
  671.  
  672. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  673.  
  674. ----- 3.2.3 vsa_wait_vsync()
  675.  
  676. Inputs:   Nothing;
  677.  
  678. Returns:  Nothing
  679.  
  680. Description:   This routine waits until the beginning of the CRTs' vertical
  681.           retrace period before returning control to the calling program.
  682.           If vsa_wait_vsync is called while the CRT is in vertical retrace,
  683.           this routine waits until the completion of the current retrace
  684.           period and the completion of the following active scan and then
  685.           returns at the beginning of the next vertical retrace period.
  686.           The programmer can use this function to precede drawing functions
  687.           which must be executed during CRT Vertical Retrace.  The
  688.           programmer is assured the full retrace time for his use.
  689.  
  690. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  691.  
  692.  
  693. ----- 3.3 Attribute Functions
  694.  
  695. ----- 3.3.1 vsa_set_color(color)
  696.  
  697. Inputs:   unsigned color;
  698.  
  699. Returns:  Nothing
  700.  
  701. Description:   This routine sets the current drawing color which is used in
  702.           drawing pixels, lines, and rectangles.  The "color" is an 8 bit
  703.           value from 0 to 255 which is used to index in to the Color Look
  704.           Up Table (see Section 3.4).
  705.  
  706. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  707.  
  708.  
  709.  
  710.                                 
  711.                                 
  712.                                 
  713.                                 
  714.                                 Page: 13
  715.                                    
  716. ----- 3.3.2 vsa_set_text_color(color)
  717.  
  718. Inputs:   unsigned color;
  719.  
  720. Returns:  Nothing
  721.  
  722. Description:   This routine sets the current text color which is used in
  723.           drawing text.  The "color" is an 8 bit value from 0 to 255 which
  724.           is used to index in to the Color Look Up Table (see Section 3.4).
  725.           Since the text is drawn using vector strokes, the background is
  726.           unaffected by newly drawn text.  Note: this also means that
  727.           drawing a text 'space' character does nothing but index the text
  728.           pointer.
  729.  
  730. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  731.  
  732. ----- 3.3.3 vsa_set_clip_mode(mode)
  733.  
  734. Inputs:   unsigned mode;
  735.  
  736. Returns:  Nothing
  737.  
  738. Description:   This routine sets the Viewport clipping mode ON if 'mode' =
  739.           1, OFF otherwise.  After vsa_init, the default is ON.
  740.  
  741. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  742.  
  743.  
  744. ----- 3.3.4 vsa_set_viewport(left, top, right, bottom)
  745.  
  746. Inputs:   int left, top, right, bottom;
  747.  
  748. Returns:  Nothing
  749.  
  750. Description:   This routine sets the global Viewport clipping parameters
  751.           XLeft, YTop, XRight, and YBottom.  Note that vsa_init initializes
  752.           these values to the full screen dimensions for the selected video
  753.           mode.  Viewport clipping is turned on and off through the
  754.           vsa_set_clip_mode function.  By default, clip mode is ON after
  755.           vsa_init.
  756.                When clip mode is ON, all items drawn on the screen through
  757.           VSA256 functions are clipped to the screen Viewport rectangle
  758.           defined by XLeft, YTop, XRight, and YBottom.
  759.  
  760. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  761.  
  762.  
  763.  
  764.                                 
  765.                                 
  766.                                 
  767.                                 
  768.                                 
  769.                                 Page: 14
  770.                                    
  771. ----- 3.4 Color Look Up Table Functions
  772.  
  773.      The Color Look Up Table consists of 256 registers and each register
  774. stores an 18 bit value defining 6 bit levels for each of red, green, and
  775. blue.  The drawing functions index into the Color Look Up Table with an 8
  776. bit value (usually set with vsa_set_color) to determine the drawing color.
  777. With the following functions, the Color Look Up Table can be read or
  778. modified one register at a time or all at once in a block operation.
  779.  
  780. ----- 3.4.1 vsa_read_color_register(index,redptr,grnptr,bluptr)
  781.  
  782. Inputs:   unsigned index;
  783.           unsigned char far *redptr, far *grnptr, far *bluptr;
  784.  
  785. Returns:  Nothing
  786.  
  787. Description:   This routine reads the value of one of the 256 color
  788.           registers as defined by 'index'.  Pointers to the red, green, and
  789.           blue components of the color are returned (6 bits each for red,
  790.           green, and blue).
  791.  
  792. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  793.  
  794. ----- 3.4.2 vsa_write_color_register(index,red,green,blue)
  795.  
  796. Inputs:   unsigned index;
  797.           unsigned char red,green,blue;
  798.  
  799. Returns:  Nothing
  800.  
  801. Description:   This routine writes the value of one of the 256 color
  802.           registers as defined by 'index'.  The calling routine provides
  803.           'red', 'green', and 'blue' components of the color (6 bits each
  804.           for red, green, and blue).
  805.  
  806. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  807.  
  808. ----- 3.4.3 vsa_read_color_block(start,count,array)
  809.  
  810. Inputs:   unsigned start,count;
  811.           unsigned char far array[];
  812.  
  813. Returns:  Nothing
  814.  
  815. Description:   This routine reads 'count' (Range: 1 to 256) consecutive
  816.           color registers starting at 'start' (Range: 0 to 255) within the
  817.           Color Look Up Table.  The 'count' must be less than or equal to
  818.           256 - 'start'.  The values read from the color registers are
  819.           returned from this routine in 'array[]'.  Each element of
  820.  
  821.  
  822.                                 
  823.                                 
  824.                                 Page: 15
  825.                                    
  826.           'array[]' is a byte, and the size of 'array[]' is equal to three
  827.           times 'count'.  Every three bytes in 'array[]' represents the
  828.           red, green, and blue color values respectively for one color
  829.           register.  Each color component (red, green, or blue) is a byte
  830.           value but only ranges from 0 to 63.
  831.  
  832. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  833.  
  834. ----- 3.4.4 vsa_write_color_block(start,count,array)
  835.  
  836. Inputs:   unsigned start,count;
  837.           unsigned char far array[];
  838.  
  839. Returns:  Nothing
  840.  
  841. Description:   This routine writes 'count' (Range: 1 to 256) consecutive
  842.           color registers starting at 'start' (Range: 0 to 255) within the
  843.           Color Look Up Table.  The 'count' must be less than or equal to
  844.           256 - 'start'.  The values loaded into the color registers are
  845.           passed to this routine in 'array[]'.  Each element of 'array[]'
  846.           is a byte, and the size of 'array[]' is equal to three times
  847.           'count'.  Every three bytes in 'array[]' represents the red,
  848.           green, and blue color values respectively for one color register.
  849.           Each color component (red, green, or blue) is a byte value but
  850.           only ranges from 0 to 63.
  851.  
  852. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  853.  
  854. ----- 3.5 Text Functions (New-Vector Stroked!)
  855.  
  856.      Text support in the VSA256 Graphics Library has been completely
  857. REVAMPED!  The library no longer relies on the video card manufacturers
  858. BIOS to get text support.  Instead each character is drawn using 2D vector
  859. strokes.  The advantages are as follows:
  860.  
  861.      - Text now works with ALL video cards!
  862.      - Now text is Infinitely scaleable.
  863.      - Text positioning resolution is down to 1 pixel.
  864.      - Background color is preserved.
  865.      - The programmer can define his own fonts in VSA_FONT.H.
  866.  
  867.      Some minor incompatibilities with VSA256 version 2.0 were introduced
  868. due to the changes and they are as follows:
  869.  
  870.      - vsa_write_string now takes x,y (in pixel coordinates)
  871.        instead of row,col (in character coordinates) as the first
  872.        two parameters.
  873.      - The vsa_write_char function was deleted.
  874.      - The supported ASCII characters are the printable
  875.        characters from ASCII code 32 to ASCII code 127.
  876.  
  877.  
  878.                                 
  879.                                 Page: 16
  880.                                    
  881.      Your existing code should take very little editing to make these
  882. changes, especially if you write a macro to edit all occurrences of
  883. vsa_write_string as follows:
  884.  
  885.      OLD - vsa_write_string(row,col,color,text);
  886.  
  887.      NEW - vsa_write_string(col*XCharSize,row*YCharSize,color,text);
  888.  
  889. ----- 3.5.1 vsa_set_text_cursor(x,y)
  890.  
  891. Inputs:   int x,y;
  892.  
  893. Returns:  Nothing
  894.  
  895. Description:   This routine sets the current text cursor position to 'x,y'
  896.           in pixel coordinates.  The current text cursor position is only
  897.           used by vsa_write_string_alt.
  898.  
  899. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  900.  
  901. Comments: Note that this function has changed to pixel coordinates to
  902.           support vector stroked fonts.
  903.  
  904. ----- 3.5.2 vsa_get_text_cursor(px,py)
  905.  
  906. Inputs:   int far *px, far *py;
  907.  
  908. Returns:  Nothing
  909.  
  910. Description:   This routine gets the current text cursor position and
  911.           returns the x and y positions via the pointers '*px' and '*py'
  912.           respectively.  The returned positions are in pixel coordinates.
  913.           The current text cursor position is only used by
  914.           vsa_write_string_alt.
  915.  
  916. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  917.  
  918. ----- 3.5.3 vsa_set_text_scale(x_scale,y_scale)
  919.  
  920. Inputs:   float x_scale, y_scale;
  921.  
  922. Returns:  Nothing
  923.  
  924. Description:   This routine sets the x and y scale factors for text drawn
  925.           with the vsa_write_string and vsa_write_string_alt routines.  The
  926.           'x_scale' and 'y_scale' scale factors are applied to the global
  927.           parameters XCharBase and YCharBase respectively to determine the
  928.           drawn text character width and height in pixels.  Since these
  929.           scale factors are floating point, continuously and infinitely
  930.           scaleable text characters are possible.
  931.  
  932.  
  933.                                 
  934.                                 Page: 17
  935.                                    
  936.                This routine automatically adjusts the global parameters
  937.           XCharSize, YCharSize, XCharResolution and YCharResolution to
  938.           their appropriate values.  After vsa_init, the x_scale and
  939.           y_scale factors both default to 1.0.
  940.  
  941. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  942.  
  943. ----- 3.5.4 vsa_set_text_cursor_mode(mode)
  944.  
  945. Inputs:   unsigned mode;
  946.  
  947. Returns:  Nothing
  948.  
  949. Description:   This routine determines the mode of the text cursor
  950.           operation.  If 'mode' is '0' (the default after calling
  951.           vsa_init), the text cursor is not updated after a new text string
  952.           is written with vsa_write_string or vsa_write_string_alt.  If
  953.           'mode' is '1', then the text cursor is moved to the end of the
  954.           text string after executing vsa_write_string or
  955.           vsa_write_string_alt.
  956.  
  957. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  958.  
  959. Comments: If the text cursor mode is set to '1', the programmer may
  960.           override the cursor operation as follows.  If a '\r' is placed at
  961.           the end of the text string, the text cursor X value will reset to
  962.           the beginning of the text string (equivalent to a carriage
  963.           return).  If a '\n' is placed at the end of the text string, the
  964.           cursor Y value advances by YCharSize pixels (equivalent to a line
  965.           feed).  Putting '\r\n' at the end of a text string results in a
  966.           line feed and carriage return.
  967.  
  968. ----- 3.5.5 vsa_write_string(x,y,color,string)
  969.  
  970. Inputs:   int x,y;
  971.           unsigned color;
  972.           char far string[];
  973.  
  974. Returns:  Nothing
  975.  
  976. Description:   This routine writes a null terminated text string 'string'
  977.           at position (x,y).  The text is written with the 'color' passed
  978.           to this routine. After execution, if the text cursor mode is '0',
  979.           the text cursor remains at 'x,y', otherwise it is set to the end
  980.           of the text string just written (see comments in section 3.5.4).
  981.  
  982. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  983.  
  984. Comments: This routine was redefined in version 3.0 to support the new
  985.           vector stroked fonts.  The text is drawn with vector strokes at
  986.  
  987.  
  988.                                 
  989.                                 Page: 18
  990.                                    
  991.           the scale factor determined by the vsa_set_text_scale routine.
  992.           Full 2D clipping is performed according to the values set with
  993.           the vsa_set_clip_mode and vsa_set_viewport routines.
  994.  
  995. ----- 3.5.6 vsa_write_string_alt(string)
  996.  
  997. Inputs:   char far string[];
  998.  
  999. Returns:  Nothing
  1000.  
  1001. Description:   This routine writes a null terminated text string 'string'
  1002.           at the current text cursor position as determined by
  1003.           vsa_set_text_cursor.  The text is written with the current text
  1004.           color.  After execution, if the text cursor mode is '0', the
  1005.           current text cursor remains unchanged, otherwise it is set to the
  1006.           end of the text string just written (see comments in section
  1007.           3.5.4).
  1008.  
  1009. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1010.  
  1011. Comments: This routine was redefined in version 3.0 to support the new
  1012.           vector stroked fonts.  The text is drawn with vector strokes at
  1013.           the scale factor determined by the vsa_set_text_scale routine.
  1014.           Full 2D clipping is performed according to the values set with
  1015.           the vsa_set_clip_mode and vsa_set_viewport routines.
  1016.  
  1017.  
  1018. ----- 3.6 Basic Drawing Functions
  1019.  
  1020. ----- 3.6.1 vsa_move_to(x,y)
  1021.  
  1022. Inputs:   int x,y;
  1023.  
  1024. Returns:  Nothing
  1025.  
  1026. Description:   This routine sets the current cursor position to 'x,y'.  The
  1027.           current cursor position is used by the vsa_line_to,
  1028.           vsa_rect_fill, and vsa_rect functions.
  1029.  
  1030. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1031.  
  1032. ----- 3.6.2 vsa_set_pixel(x,y)
  1033.  
  1034. Inputs:   int x,y;
  1035.  
  1036. Returns:  Nothing
  1037.  
  1038. Description:   This routine draws a single pixel at 'x,y' with the current
  1039.           drawing color.
  1040.  
  1041. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1042.  
  1043.  
  1044.                                 Page: 19
  1045.                                    
  1046. ----- 3.6.3 vsa_get_pixel(x,y)
  1047.  
  1048. Inputs:   int x,y;
  1049.  
  1050. Returns:  unsigned color;
  1051.  
  1052. Description:   This routine returns the current pixel value at screen
  1053.           coordinates 'x,y'.
  1054.  
  1055. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  1056.  
  1057. Comments: Unpredictable things may happen if you try to get a pixel that is
  1058.           outside of the XResolution-1,YResolution-1 screen dimensions.
  1059.  
  1060. ----- 3.6.4 vsa_line_to(x,y)
  1061.  
  1062. Inputs:   int x,y;
  1063.  
  1064. Returns:  Nothing
  1065.  
  1066. Description:   This routine draws a line from the current cursor position
  1067.           to 'x,y' with the current drawing color.  Then the current cursor
  1068.           position is moved to 'x,y'.
  1069.                The drawing speed of this routine is up to 3 times faster
  1070.           than that of the vsa_line_to function in VSA256 Graphics Library
  1071.           Version 1.1.
  1072.  
  1073. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1074.  
  1075. ----- 3.6.5 vsa_gouraud_line(x0,c0,x1,c1,y)
  1076.  
  1077. Inputs:   int x0,c0,x1,c1,y
  1078.  
  1079. Returns:  Nothing
  1080.  
  1081. Description:   This routine draws a color interpolated line from the 'x0,y'
  1082.           to 'x1,y1'.  The pixel color value is linearly varied from a
  1083.           starting value of 'c0' at 'x0,y' to an ending value of 'c1' at
  1084.           'x1,y'.  This technique of color interpolation is named Gouraud
  1085.           shading after the famous Joe-Bob* Gouraud ... a French guy.
  1086.           Valid values for 'c0' and 'c1' are 0 through 255 and serve as
  1087.           indexes into the Color Look Up Table.  Gouraud shaded lines serve
  1088.           as a fundamental drawing element for realistic 3-D graphics.  The
  1089.           current cursor position remains unaffected by this routine.
  1090.  
  1091. Availability:  In VSA256 Graphics Library Version 2.0 and up.
  1092.  
  1093.  
  1094.  
  1095.                                 
  1096.                                 
  1097. _______________________________
  1098. * Not Really!
  1099.                                 Page: 20
  1100.                                    
  1101. ----- 3.6.6 vsa_rect_fill(x,y)
  1102.  
  1103. Inputs:   int x,y;
  1104.  
  1105. Returns:  Nothing
  1106.  
  1107.           Description:   This routine draws a filled rectangle from the current
  1108.           cursor position to the rectangles diagonal position 'x,y' with
  1109.           the current color.
  1110.  
  1111. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1112.  
  1113. ----- 3.6.7 vsa_rect(x,y)
  1114.  
  1115. Inputs:   int x,y;
  1116.  
  1117. Returns:  Nothing
  1118.  
  1119. Description:   This routine draws a rectangle from the current cursor
  1120.           position to the rectangles diagonal position 'x,y' with the
  1121.           current color.
  1122.  
  1123. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1124.  
  1125. ----- 3.6.8 vsa_triangle_fill(x0,y0,x1,y1,x2,y2)
  1126.  
  1127. Inputs:   int x0,y0,x1,y1,x2,y2
  1128.  
  1129. Returns:  Nothing
  1130.  
  1131. Description:   This routine draws a filled triangle defined by the 3
  1132.           vertices 'x0,y0', 'x1,y1', and 'x2,y2'.  The triangle is drawn
  1133.           with the current drawing color.  The current cursor position
  1134.           remains unaffected by this routine.
  1135.  
  1136. Availability:  In VSA256 Graphics Library Version 2.0 and up.
  1137.  
  1138. ----- 3.6.9 vsa_shaded_triangle(x0,y0,c0,x1,y1,c1,x2,y2,c2)
  1139.  
  1140. Inputs:   int x0,y0,c0,x1,y1,c1,x2,c2,y2
  1141.  
  1142. Returns:  Nothing
  1143.  
  1144. Description:   This routine draws a color interpolated triangle defined by
  1145.           the 3 vertices 'x0,y0', 'x1,y1', and 'x2,y2'.  The pixel color
  1146.           value is linearly varied in 2 dimensions across the surface of
  1147.           the triangle using the values 'c0', 'c1', and 'c2' as the
  1148.           starting colors at the respective vertices.  This technique of
  1149.           color interpolation is named Gouraud shading after the famous Joe-
  1150.           Bob* Gouraud ... a French guy.  Valid values for 'c0', 'c1', and
  1151.  
  1152. _______________________________
  1153. * Not Really!
  1154.                                 Page: 21
  1155.                                    
  1156.           'c2' are 0 through 255 and serve as indexes into the Color Look
  1157.           Up Table.  Gouraud shaded triangles serve as a fundamental
  1158.           drawing element for realistic 3-D graphics.  (Basically, most 3-D
  1159.           surfaces can be constructed out of shaded triangles).  The
  1160.           current cursor position remains unaffected by this routine.
  1161.  
  1162. Availability:  In VSA256 Graphics Library Version 2.0 and up.
  1163.  
  1164. ----- 3.6.10 vsa_h_line(y,x0,x1)
  1165.  
  1166. Inputs:   int y,x0,x1;
  1167.  
  1168. Returns:  Nothing
  1169.  
  1170. Description:   This routine draws a horizontal line from 'x0,y' to 'x1,y'.
  1171.           The line is drawn with the current drawing color.  For horizontal
  1172.           lines this function is quicker than the vsa_line_to function.
  1173.                The drawing speed of this routine is up to 3 times faster
  1174.           than that of the vsa_h_line function in VSA256 Graphics Library
  1175.           Version 1.1.
  1176.  
  1177. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1178.  
  1179. ----- 3.6.11 vsa_v_line(x,y0,y1)
  1180.  
  1181. Inputs:   int x,y0,y1;
  1182.  
  1183. Returns:  Nothing
  1184.  
  1185. Description:   This routine draws a vertical line from 'x,y0' to 'x,y1'.
  1186.           The line is drawn with the current drawing color.  For vertical
  1187.           lines this function is quicker than the vsa_line_to function.
  1188.  
  1189. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1190.  
  1191. ----- 3.7 Specialized Drawing Functions
  1192.  
  1193. ----- 3.7.1 vsa_raster_line(x0,x1,y,array)
  1194.  
  1195. Inputs:   int x0,x1,y;
  1196.                     unsigned char far array[];
  1197.  
  1198. Returns:  Nothing
  1199.  
  1200. Description:   This routine draws a horizontal raster line from 'x0,y' to
  1201.           'x1,y'.  The 'array[]' values specify each pixel's color value.
  1202.           If x0 <= x1, then 'array[0]' defines the color of the first pixel
  1203.           in the line at 'x0,y'.  If x1 < x0, then 'array[0]' defines the
  1204.           color of the first pixel in the line at 'x1,y'.  The
  1205.           vsa_raster_line routine is typically used to draw images on the
  1206.                                 
  1207.                                 
  1208.                                 
  1209.                                 Page: 22
  1210.                                    
  1211.           display one raster line at a time.
  1212.                The drawing speed of this routine is up to 2 times faster
  1213.           than that of the vsa_raster_line function in VSA256 Graphics
  1214.           Library Version 1.1.
  1215.  
  1216. Availability:  In VSA256 Graphics Library Version 1.0 and up.
  1217.  
  1218. ----- 3.7.2 vsa_get_raster_line(x0,x1,y,array)
  1219.  
  1220. Inputs:   int x0,x1,y;
  1221.           unsigned char far array[];
  1222.  
  1223. Returns:  Nothing
  1224.  
  1225. Description:   This routine gets a horizontal raster line from 'x0,y' to
  1226.           'x1,y'.  The 'array[]' is loaded with each pixel's color value.
  1227.           If x0 <= x1, then 'array[0]' defines the color of the first pixel
  1228.           in the line at 'x0,y'.  If x1 < x0, then 'array[0]' defines the
  1229.           color of the first pixel in the line at 'x1,y'.  The
  1230.           vsa_get_raster_line routine is typically used to read back images
  1231.           already drawn on the display one raster line at a time.
  1232.  
  1233. Availability:  In VSA256 Graphics Library Version 2.0 and up.
  1234.  
  1235. Comments: This routine limits x0 and x1 within the range of 0 and
  1236.           XResolution-1. If x0 goes negative, the first element of 'array'
  1237.           holds the pixel at x=0 and less than x1-x0+1 pixels will be
  1238.           loaded  into 'array'.  Likewise, if x1 is greater than
  1239.           XResolution-1, less than x1-x0+1 pixels will be loaded  into
  1240.           'array'.
  1241.  
  1242. ----- 3.7.3 vsa_image_size(x0,y0,x1,y1)
  1243.  
  1244. Inputs:   int x0,y0,x1,y1;
  1245.  
  1246. Returns:  unsigned long image_size;
  1247.  
  1248. Description:   This routine calculates the size of the image defined within
  1249.           a rectangle bound by 'x0,y0' and 'x1,y1'.  The size of the image
  1250.           plus 4 is returned.
  1251.                The vsa_image_size routine is typically used to determine
  1252.           the size of the image array to be allocated and used in the
  1253.           vsa_get_image and vsa_put_image routines.
  1254.  
  1255. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  1256.  
  1257.                                 
  1258.                                 
  1259.                                 
  1260.                                 
  1261.                                 
  1262.                                 
  1263.                                 
  1264.                                 Page: 23
  1265.                                    
  1266. ----- 3.7.4 vsa_get_image(x0,y0,x1,y1,image_array)
  1267.  
  1268. Inputs:   int x0,y0,x1,y1;
  1269.           unsigned char huge *image_array;
  1270.  
  1271. Returns:  Nothing
  1272.  
  1273. Description:   This routine gets the image defined in the rectangle 'x0,y0'
  1274.           to 'x1,y1' and stores it in the memory buffer pointed to by
  1275.           'image_array'.  The memory for 'image_array' must be allocated
  1276.           prior to this call.  Upon returning from this routine, the first
  1277.           2 bytes of the 'image_array' buffer contain the image width, and
  1278.           the second 2 bytes contain the image height.  The remaining bytes
  1279.           in the 'image_array' buffer hold the image pixel data.
  1280.                The vsa_get_image routine is typically used in conjunction
  1281.           with the vsa_put_image routine for BitBLT operations.
  1282.  
  1283. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  1284.  
  1285. Comments: This routine clamps x0, y0, x1, and y1 to zero.  If any of these
  1286.           parameters are less than zero, vsa_get_image overrides them with
  1287.           zero and less than (x1-x0+1)*(y1-y0+1) pixels will be  loaded
  1288.           into 'image_array'.  No clamping of x0, y0, x1, and y1 is
  1289.           performed at XResolution-1 and YResolution-1 so that off screen
  1290.           memory can be used as scratch pad area.
  1291.  
  1292. ----- 3.7.5 vsa_put_image(x0,y0,image_array,raster_op)
  1293.  
  1294. Inputs:   int x0,y0;
  1295.           unsigned raster_op;
  1296.           unsigned char huge *image_array;
  1297.  
  1298. Returns:  Nothing
  1299.  
  1300. Description:   This routine gets the image defined in the 'image_array'
  1301.           buffer and displays it starting at screen coordinates 'x0,y0'.
  1302.           The image width and height are determined by the first two 16 bit
  1303.           words of the 'image_array' buffer.  The 'raster_op' parameter
  1304.           determines how the data in the 'image_array' buffer are merged
  1305.           with the existing screen data.
  1306.  
  1307.           raster_op      Function
  1308.           0              Replace existing data.
  1309.           1              AND with existing data.
  1310.           2              OR with existing data.
  1311.           3              XOR with existing data.
  1312.           4              Reserved .... Do Not Use !!
  1313.           5              Reserved .... Do Not Use !!
  1314.  
  1315.                The vsa_put_image routine is typically used in conjunction
  1316.           with the vsa_get_image routine for BitBLT operations.
  1317.  
  1318. Availability:  In VSA256 Graphics Library Version 3.0 and up.
  1319.                                 Page: 24
  1320.                                    
  1321.  
  1322. ----- 4.0 Nitty Gritties
  1323.  
  1324. ----- 4.1 Registration Information
  1325.  
  1326.      If you find the VSA256 Graphics Library useful, a registration of $29
  1327. would be appreciated.  Registration brings with it MAJOR BENEFITS, as
  1328. spelled out in section 1.2, so look at the ORDER.TXT file and fill it out!
  1329.  
  1330.           Please fill out the Information About You and the Wish List
  1331. sections, and indicate the version number of the software you are presently
  1332. using.  Send check or money order to:
  1333.  
  1334.                                 Spyro Gumas
  1335.                           1668 Shady Brook Drive
  1336.                            Fullerton, Ca. 92631
  1337.                                      
  1338.                                 
  1339.                                 
  1340.                                 
  1341.                                 
  1342.                                 
  1343.                                 
  1344.                                 
  1345.                                 
  1346.                                 
  1347.                                 
  1348.                                 
  1349.                                 
  1350.                                 
  1351.                                 
  1352.                                 
  1353.                                 
  1354.                                 
  1355.                                 
  1356.                                 
  1357.                                 
  1358.                                 
  1359.                                 
  1360.                                 
  1361.                                 
  1362.                                 
  1363.                                 
  1364.                                 
  1365.                                 
  1366.                                 
  1367.                                 
  1368.                                 
  1369.                                 
  1370.                                 
  1371.                                 
  1372.                                 
  1373.                                 
  1374.                                 Page: 25
  1375.                                    
  1376. ----- 4.2 Software License
  1377.  
  1378.                  VSA256 Graphics Library, Version 3.0
  1379.      Copyright Spyro Gumas, 1992 - 1994.  All Rights Reserved.
  1380.  
  1381.       The  VSA256 Graphics Library is a "shareware program" and is provided
  1382. at  no  charge to the user for evaluation.  The essence of "user-supported"
  1383. software  is  to  provide  personal computer users  with  quality  software
  1384. without  high  prices,  and  yet to provide incentive  for  programmers  to
  1385. continue to develop new products.  If you find this program useful and find
  1386. that  you  are using The VSA256 Graphics Library and continue  to  use  The
  1387. VSA256  Graphics Library after a reasonable trial period, you must  make  a
  1388. registration payment of $29 to Spyro Gumas.  The $29 registration fee  will
  1389. license  one  copy for use on any one computer at any one time.   You  must
  1390. treat this software just like a book.  An example is that this software may
  1391. be  used  by any number of people and may be freely moved from one computer
  1392. location to another, so long as there is no possibility of it being used at
  1393. one  location  while it's being used at another. Just as a book  cannot  be
  1394. read by two different persons at the same time.
  1395.  
  1396. You are free (and encouraged) to copy and distribute the VSA256 Graphics
  1397. Library if:
  1398.  
  1399. 1)   It is not used as a component of another software library.
  1400. 2)   No fee is charged for use, copying or distribution.
  1401. 3)   It is distributed as is (preferably as VSA256.ZIP) and not
  1402.      modified in any way.
  1403.  
  1404. Furthermore, you are granted royalty free use of The VSA256 Graphics
  1405. Library executable code in any of your programs given that:
  1406.  
  1407. 1)   You have registered your use of The VSA256 Graphics Library
  1408.      and paid the $29 registration fee.
  1409. 2)   It is not used as a component of another software library.
  1410. 3)   You visibly acknowledge the use of The VSA256 Graphics
  1411.      Library in your product in both the printed materials and
  1412.      the executable software with the   following statement:
  1413.  
  1414.      "This software uses the VSA256 Graphics Library,
  1415.       Copyright Spyro Gumas, 1992 - 1994.  All Rights Reserved"
  1416.  
  1417.  
  1418.      Clubs and user groups may charge a nominal fee (not to exceed $10) for
  1419. expenses  and  handling  while distributing the  VSA256  Graphics  Library.
  1420. Anyone   distributing  The  VSA256  Graphics  Library  for  any   kind   of
  1421. remuneration  must  first  contact Spyro Gumas at  the  address  below  for
  1422. authorization.  This  authorization  will  be  automatically   granted   to
  1423. distributors  recognized by the (ASP) as adhering  to  its  guidelines  for
  1424.                                 
  1425.                                 
  1426.                                 
  1427.                                 
  1428.                                 
  1429.                                 Page: 26
  1430.                                    
  1431. shareware distributors, and such distributors may begin offering The VSA256
  1432. Graphics Library immediately (However Spyro Gumas must still be advised  so
  1433. that the distributor can be kept up-to-date with the latest version of  The
  1434. VSA256 Graphics Library.).
  1435.  
  1436.       Commercial users of The VSA256 Graphics Library must register and pay
  1437. for their copies of The VSA256 Graphics Library within 30 days of first use
  1438. or  their  license  is  withdrawn.  Consult the  file  ORDER.TXT  for  more
  1439. information or contact Spyro Gumas.
  1440.  
  1441. ----- 4.3 Disclaimer
  1442.  
  1443.      Users of The VSA256 Graphics Library must accept this  disclaimer of
  1444. warranty:  The VSA256 Graphics Library is supplied as is.  The author
  1445. disclaims all warranties, expressed or implied, including, without
  1446. limitation, the warranties of merchantability and of fitness for any
  1447. purpose. The author assumes no liability for damages, direct or
  1448. consequential, which may result from the use of The VSA256 Graphics
  1449. Library.  In no event shall the author's liability for any damages ever
  1450. exceed the price paid for the license to use The VSA256 Graphics Library,
  1451. regardless of the form of the claim.  The person using The VSA256 Graphics
  1452. Library bears all risk as to the quality and performance of this software.
  1453.  
  1454. ----- 4.4 Technical Support
  1455.  
  1456.      If you have any questions or comments about the VSA256 Graphics
  1457. Library, please write me at:
  1458.  
  1459.                                 Spyro Gumas
  1460.                           1668 Shady Brook Drive
  1461.                            Fullerton, Ca. 92631
  1462.  
  1463. Or, contact me on EMAIL!
  1464.  
  1465.             CompuServe:    71064,1571
  1466.             Internet:      71064.1571@compuserve.com
  1467.                                 
  1468.                                 
  1469.                                 
  1470.                                 
  1471.                                 
  1472.                                 
  1473.                                 
  1474.                                 
  1475.                                 
  1476.                                 
  1477.                                 
  1478.                                 
  1479.                                 
  1480.                                 
  1481.                                 
  1482.                                 
  1483.                                 
  1484.                                 Page: 27
  1485.                                    
  1486. ----- 5.0 Graphics Library Extensions
  1487.  
  1488.      The VSA256 Graphics Library is a base library which is supported by
  1489. library extensions for more specialized tasks.  New extensions will be
  1490. developed periodically.  The current extensions are:
  1491.  
  1492. *** TIFF256 Graphics Library Extension 3.0 *** This library extension
  1493. provides functions which operate with Tagged Image File Format (TIFF)
  1494. images.  With these functions, you can traverse the image file, extract
  1495. image information, and display the images as part of your own program.  You
  1496. can also modify the TIFF images and write them back to TIFF files.
  1497. Furthermore, any image that you generate with VSA256 can be saved as a TIFF
  1498. file.  The image types supported include Bilevel, Grayscale, Palette Color
  1499. and RGB True Color.  Version 3.0 adds Adaptive Color Palette generation
  1500. when reading in 24 bit images.  This makes most True Color images show up
  1501. undistorted by the 256 color limitation.  Now the fully capable version of
  1502. the TIFF256 Graphics Library Extensions is shareware, available from the
  1503. same place that you got the VSA256 Graphics Library.
  1504.  
  1505. *** CBTMouse API Library 1.0 *** New from CyberBase Technologies, Inc.,
  1506. this library adds complete mouse interaction to your graphics applications.
  1507. These guys go all out to make mouse driven graphics programming a breeze.
  1508. Functions provided include initialization, displaying and hiding mouse,
  1509. reading position, setting position, reading button status, working within
  1510. bounding boxes, changing cursor color and size, and waiting for various
  1511. mouse inputs.  You get a very functional version of this library when you
  1512. register for the VSA256 Graphics Library.  The full up library (version
  1513. 1.0) is shipped by CyberBase Technologies, Inc. upon a nominal registration
  1514. fee.
  1515.  
  1516. *** CBT3D Library 1.0 *** Also from CyberBase Technologies, Inc. (yeah,
  1517. these guys are busy), this library lets you write 3D applications.  What
  1518. ever your interests, Mechanical Design, Architecture, Interior Design,
  1519. Space Widgets, you name it, you can do it.  Functions provided let you add
  1520. and delete objects from a display list, set the view point, and perform 3D
  1521. transformations including scale, offset, and rotation.  Select the drawing
  1522. mode for the 3D objects from Wireframe, Solid, or Gouraud (smooth) Shaded.
  1523. You get a very functional version of this library when you register for the
  1524. VSA256 Graphics Library.  The full up library (version 1.0) is shipped by
  1525. CyberBase Technologies, Inc. upon a nominal registration fee.
  1526.                                 
  1527.                                 
  1528.                                 
  1529.                                 
  1530.                                 
  1531.                                 
  1532.                                 
  1533.                                 
  1534.                                 
  1535.                                 
  1536.                                 
  1537.                                 
  1538.                                 
  1539.                                 Page: 28
  1540.                                    
  1541. ----- 6.0 Appendix
  1542.  
  1543. ----- 6.1 VSA.H Include File
  1544.  
  1545. /*.................................. VSA.H ................. 7-2-94 ........*/
  1546. /* This file declares the VSA256 Graphics Library functions and global      */
  1547. /* parameters used throughout the graphics routines.                        */
  1548. /*                                                                          */
  1549. /*                               VERSION 3.0                                */
  1550. /*                                                                          */
  1551. /*         Copyright Spyro Gumas, 1992 - 1994.  All Rights Reserved.        */
  1552. /*..........................................................................*/
  1553.  
  1554. /*..........................................................................*/
  1555. /*                    External Function Prototypes                          */
  1556. /*..........................................................................*/
  1557.  
  1558. extern unsigned  far cdecl vsa_set_svga_mode( unsigned );
  1559. extern unsigned  far cdecl vsa_get_svga_mode( unsigned far * );
  1560. extern unsigned  far cdecl vsa_set_display_start( unsigned, unsigned );
  1561. extern unsigned  far cdecl vsa_get_display_start( unsigned far *,
  1562.                             unsigned far * );
  1563. extern unsigned  far cdecl vsa_init( unsigned );
  1564. extern void far cdecl vsa_set_color( unsigned );
  1565. extern void far cdecl vsa_set_text_color( unsigned );
  1566. extern void far cdecl vsa_set_text_cursor_mode( unsigned );
  1567. extern void far cdecl vsa_set_text_cursor( int, int);
  1568. extern void far cdecl vsa_get_text_cursor( int far *, int far *);
  1569. extern void far cdecl vsa_set_text_scale(float,float);
  1570. extern void far cdecl vsa_set_viewport( int, int, int, int);
  1571. extern void far cdecl vsa_set_clip_mode(  unsigned );
  1572. extern void far cdecl vsa_write_string( int, int, int, char far * );
  1573. extern void far cdecl vsa_write_string_alt( char far * );
  1574. extern void far cdecl vsa_read_color_register( unsigned, unsigned char far *,
  1575.                  unsigned char far *, unsigned char far *);
  1576. extern void far cdecl vsa_write_color_register( unsigned, unsigned char,
  1577.                  unsigned char, unsigned char );
  1578. extern void far cdecl vsa_read_color_block( unsigned, unsigned,
  1579.                  unsigned char far * );
  1580. extern void far cdecl vsa_write_color_block( unsigned, unsigned,
  1581.                  unsigned char far * );
  1582. extern void far cdecl vsa_move_to( int, int);
  1583. extern void far cdecl vsa_set_pixel( int, int);
  1584. extern unsigned far cdecl vsa_get_pixel( int, int);
  1585. extern void far cdecl vsa_line_to( int, int);
  1586. extern void far cdecl vsa_triangle_fill( int, int, int, int, int, int);
  1587. extern void far cdecl vsa_rect_fill( int, int);
  1588. extern void far cdecl vsa_rect( int, int);
  1589. extern unsigned long far cdecl vsa_image_size( int, int, int, int);
  1590.                                 
  1591.                                 
  1592.                                 
  1593.                                 
  1594.                                 Page: 29
  1595.                                    
  1596. extern void far cdecl vsa_get_image( int, int, int, int,
  1597.                  unsigned char huge * );
  1598. extern void far cdecl vsa_put_image( int, int,unsigned char huge *, unsigned);
  1599. extern void far cdecl vsa_h_line( int, int, int);
  1600. extern void far cdecl vsa_v_line( int, int, int);
  1601. extern void far cdecl vsa_raster_line( int, int, int, unsigned char far *);
  1602. extern void far cdecl vsa_get_raster_line( int, int, int,unsigned char far *);
  1603. extern void far cdecl vsa_gouraud_line( int, int, int, int, int);
  1604. extern void far cdecl vsa_shaded_triangle( int, int, int, int, int, int,
  1605.                                            int, int, int);
  1606. extern void far cdecl vsa_wait_hsync( void );
  1607. extern void far cdecl vsa_wait_vsync( void );
  1608. extern void far cdecl vsa_about( void );
  1609.  
  1610. /*..........................................................................*/
  1611. /*                    External Parameter Declarations                       */
  1612. /*..........................................................................*/
  1613. extern unsigned far XResolution, far YResolution;
  1614. extern unsigned far XCharResolution, far YCharResolution;
  1615. extern unsigned char far XCharSize, far YCharSize;
  1616. extern unsigned char far BitsPerPixel;
  1617. extern int far XLeft, far XRight, far YTop, far YBottom;
  1618. extern float far Text_X_Scale, far Text_Y_Scale;
  1619.  
  1620.  
  1621.                                 
  1622.                                 
  1623.                                 
  1624.                                 
  1625.                                 
  1626.                                 
  1627.                                 
  1628.                                 
  1629.                                 
  1630.                                 
  1631.                                 
  1632.                                 
  1633.                                 
  1634.                                 
  1635.                                 
  1636.                                 
  1637.                                 
  1638.                                 
  1639.                                 
  1640.                                 
  1641.                                 
  1642.                                 
  1643.                                 
  1644.                                 
  1645.                                 
  1646.                                 
  1647.                                 
  1648.                                 
  1649.                                 Page: 30
  1650.                                    
  1651. ----- 6.2 VSA_FONT.H Include File
  1652.  
  1653. /*............................... VSA_FONT.H .............. 6-25-94 ........*/
  1654. /*    This is the font file for the VSA256 Graphics Library.  The basic     */
  1655. /*  font size is set by the XCharBase and YCharBase values defined at the   */
  1656. /*  top of this file.  This include file gives you the ability to fully     */
  1657. /*  customize your fonts! Feel free to edit the font vertex lists to be as  */
  1658. /*  personalized as possible.  Read on to see how it works.                 */
  1659. /*                                                                          */
  1660. /*   ASC[M][N] is a 2 dimensional array.  The M index selects one of 96     */
  1661. /* possible characters and corresponds to the printable ASCII character     */
  1662. /* codes from 32 to 127. (M = 0 selects ASCII character code 32 ... a space,*/
  1663. /* M = 95 selects ASCII character code 127 ... DEL)                         */
  1664. /*   For any given value of M, the N index steps through the vertex list    */
  1665. /* for that character.  Each vertex takes up 3 locations.  The first of     */
  1666. /* the 3 values is the blank code. A blank code of 0 means start a new line */
  1667. /* segment (equivalent to "move_to").  A blank code of 1 means continue     */
  1668. /* drawing (equivalent to "line_to").  A blank code of 255 means END of     */
  1669. /* vertex list. You MUST end each vertex list this way!                     */
  1670. /*   The next two values are x and y coordinates relative to the top left   */
  1671. /* corner of the character cell.  The x and y values should never be more   */
  1672. /* than XCharBase-1 and YCharBase-1 respectively.  When the blank code is   */
  1673. /* 255, the x and y values are ignored.  A maximum of 23 verticies plus an  */
  1674. /* END vertex are allowed per character.  Overrunning this limit will       */
  1675. /* probably cause your PC to go woopie.                                     */
  1676. /*..........................................................................*/
  1677.  
  1678. unsigned XCharBase = 8, YCharBase = 16;
  1679. unsigned char ASC[96][72]=  ... Array initialization not printed here for ...
  1680.                             ... brevity.  See VSA_FONT.H file for details ...
  1681.                                 
  1682.                                 
  1683.                                 
  1684.                                 
  1685.                                 
  1686.                                 
  1687.                                 
  1688.                                 
  1689.                                 
  1690.                                 
  1691.                                 
  1692.                                 
  1693.                                 
  1694.                                 
  1695.                                 
  1696.                                 
  1697.                                 
  1698.                                 
  1699.                                 
  1700.                                 
  1701.                                 
  1702.                                 
  1703.                                 
  1704.                                 Page: 31
  1705.